Shareware Overload Trio 2/Shareware Overload Trio Volume 2 (Chestnut CD-ROM).ISO/dir24/paket61.zip/MAN07@.EXE/MAN07.DOC

Text File | 1994-08-15 | 91KB | 2,465 lines

PART VII - SCRIPT PROCESSING
Overview
   paKet includes a simple Script processing facility. The key word there
   is "simple".  Script is a special language that paKet interprets,
   allowing it to process a pre-written set of commands.  The concept is
   the same as the BATCH facility in DOS where we can store a sequence of
   DOS commands in a BAT file.

   A Script file contains one or more Script commands and usually has a
   .SCP extension.  A Script is written in plain, ASCII text so you can use
   any text editor to create or modify a Script file.

   It is not a complex language and it is certainly NOT a sophisticated
   compiler.  The degree of error checking is not to be even compared to a
   formal language compiler or assembler. I am relying on you to check out
   your own Scripts and get the syntax correct.  If paKet detects something
   strange it usually gives you enough information to help fix the problem
   but occasionally it might just abort the Script where the problem is
   detected.

   In practice it is not as bad as it sounds.   Most Script commands are
   rather simple, so any problems are usually pretty obvious when they
   occur.  Start out with some simple Scripts, to get the feel of it and
   then you can develop more complex Scripts as you gain experience.  Many
   paKet users have written Scripts without problems so I am sure you too
   can join the ranks of successful paKet Script-writers.

   The Script facility should be sufficiently flexible to allow a variety
   of operations, given a little imagination.  So if you do develop a
   "good" Script file of your own, why not spread it around?  Broadcast it
   to other users (I suggest a Bulletin addressed to PAKET rather than to
   ALL would attract the attention of paKet users). I would appreciate it
   if you could let me have a copy too, in case I miss your Bulletin.

   In this section of the Manual, we will be looking at some examples in a
   Tutorial format to see what can be done with Scripts and to demonstrate
   the syntax required.  You might like to have a look at these and then
   with the ideas offered here you can go create some of your own.  Or even
   easier, take one that NEARLY does what you want and alter it to suit. It
   doesn't matter, you might not even use Scripts at all, but I am sure you
   will find it challenging and fun, even creative. At least give it a try.

   Various Script commands will be introduced as we examine the sample
   Scripts.  And there is a full command reference at the end of this
   section of the Manual.

   A final word, before we get into the detail... it is probably obvious to
   you by now but just in case, let me state quite clearly:  you do NOT
   need to use Scripts if you don't want to.  It is NOT necessary to even
   read this section of the Manual.  This is one of the more advanced
   features of paKet so if you feel a bit threatened or confused by all
   this talk of Scripts and Programming, just take a Valium and skip to
   another part of the Manual.

                               Page 241

Running a Script File.
   Press <Alt-S> to commence processing a Script you have available.

   A Directory Window will appear to help you select the wanted Script.
   Highlight the desired Script filename (selecting another directory if
   necessary) and press <Enter>. paKet will load and run that Script file.

   I recommend you keep all your Scripts in their own directory.  So when
   the Directory Window appears, it will be easy to find and select the
   Script you want.  It will be easier to manage too if you use the .SCP
   extension for all your Scripts as paKet recognises this by default.

   The word "SCRIPT" will be displayed in the Status Window to the left of
   the time display while the Script is running.   When the Script has
   completed, the indicator in the Status Window will disappear and you
   will be returned to normal communications.






































                               Page 242

Script Tutorial - the S command

   To start with, let's look at a very simple Script:

         S MCON OFF
         S CONOK ON

   In this section of the Manual I will indent the sample Scripts to
   help separate the Script from my comments.  But when you are writing
   your own Script, begin your Script commands in the first character
   position of the line.

   This first Script file consists of just two lines, two Send commands.
   Yes, the "S" is a Script command to "Send" the rest of that line to the
   TNC.

   Most Script commands are single letter commands.  In the case of the S
   command there is one parameter - that is the string which occupies the
   rest of the line, starting from the first non-blank character.  Oh, I
   should mention too that the Script commands may be typed in either
   upper or lower case, so the Send command can be "S" or "s".

   When you run a Script, paKet will always start at the top, the first
   line.  In this example, paKet will:

      - process that first Send command by sending the text "MCON OFF" to
        the TNC.  It will automatically generate and send <Enter> at the
        end of each Send line.

      - it will drop down to the next line.  This is another Send command
        so the text "CONOK ON" will be sent to the TNC, followed by the
        <Enter>.

      - as there are no more lines in the Script,  paKet will terminate
        Script processing and return to normal communications mode.


   That's not too hard now, is it?


  Review
   In this part:
      We introduced the S command.

   This command:
      The S command is used to Send text to the TNC.

   The syntax required:
      S text
    eg:
      S CONVERSE
      s Hello. My name is Tony.


                               Page 243

 Practical exercise
   OK, that's enough theory to get us going.  You already have enough
   information to create and run a Script!   So, let's try a practical
   exercise.

   We are going to create a Script file, then we are going to run it.

   Before we start we need to establish a few prerequisites:
      I am assuming here that you have a text editor available and that
      you know how to use it.

      And I am assuming you have configured your paKet system so there is
      a Scripts directory somewhere on your disk.  If you have not yet
      done that, press <F9> now to get the DOS prompt and Make a new
      SCRIPTS directory.  Then as we continue with this Tutorial, the new
      Scripts you create can go into that new directory.

      Check your Directories and Files Configuration (<Alt-Z> then 8) to
      verify you have specified that path as your Scripts directory.


   Now, using your text editor, create a new file in your Scripts
   directory (use paKet's <Alt-E> command to call up your editor).  Name
   it FIRST.SCP and type in the two lines of S commands as shown in the
   example above.  Don't forget it is better if you commence typing these
   commands in column 1.  Save the file and return to paKet.

   You have created your first Script!

   To run this Script, press <Alt-S> and you will see paKet's Directory
   Window pop up.  If that is not showing your Scripts Directory, change
   to that directory before continuing. (Normally paKet will display the
   directory you used last time you ran a Script, but if this is the first
   time, you might have to go find it yourself).

   Now that we have your SCRIPTS directory on the screen you should see
   your file FIRST.SCP in that directory.  To run that Script, all you
   have to do is select that file.  That is, move the highlight bar to
   that file and press <Enter>.

   paKet will load and run that Script and you will see the two commands
   appear on the screen as they are sent to the TNC and you will probably
   see the TNC's responses.

   When that is finished you are back in paKet's normal communications
   mode.   Easy huh?








                               Page 244

Script Tutorial - the B and D commands

   When you ran that first Script you might have noticed a couple of
   problems.

   Firstly, we are sending some commands to the TNC, but what if the TNC
   was not in Command Mode to start with?  if we were unlucky we could be
   sending "MCON OFF" etc to the radio for transmission and the whole
   world will be watching our mistake!

   So it is a good technique, when planning to send a TNC command, to
   ensure our TNC is in Command Mode to start with.  If we were doing this
   manually we would type <Alt-B> at the keyboard to send a BREAK code to
   the TNC.  In a Script, we can use the "B" command to do the same thing.

   So let's add the following line to the beginning of our Script:

         B

   Just a single character on that line.  That's all we need here because
   the B command has no parameters.

   You will notice when running that Script, that paKet will send the
   first command (MCON OFF) followed almost immediately by the second
   command.  This is OK and the TNC will accept our second command even
   though it has not yet had time to process the first one.  But we will
   see our second command appear on the screen before we see the TNC's
   response to the first one.  It does not look nice and tidy on the
   screen - it's out of sequence.

   With just two Send commands it probably doesn't matter too much... we
   could cope with that, even if it doesn't look too good.  But if we had
   ten or twenty or more commands to send, I think it would be worth the
   trouble to add some delays to our Script.

   One way to add a delay is the "D" command.  This command will delay for
   a specified number of seconds. So if we add:

           D 3

   to our Script after each of the commands, paKet would delay for 3
   seconds before proceeding to the next line.  That 3 second delay should
   be sufficient time for our TNC to process the previous command and send
   its acknowledgement to paKet's display.

   So our first Script would now look something like:

         B
         D 3
         S MCON OFF
         D 3
         S CONOK ON


                               Page 245

   Now, our Script will issue a BREAK code to the TNC to ensure we are in
   Command Mode and delay for 3 seconds to give the TNC time to do that.
   Then after sending that first command it will wait for 3 seconds before
   sending the second command.  That is an improvement on our first
   attempt, although it takes longer to run.

  Review:
   In this part:
      We introduced the B and D commands.

   These commands:
      The B command is similar to the <Alt-B> command we can type on the
      keyboard.  It ensures the TNC is in Command Mode.

      The D command causes a delay in the Script processing for a
      specified number of seconds.


   The syntax required:
      for the B command:
         B      (just a single character -
                 there are no other parameters required)

      for the D command:
         D seconds
       eg:
         D 3
         D 60

      There is another form of the D command we have not used here.  This
      form allows you to delay UNTIL a certain time of day.  To do that
      you type the D command as follows:
         D hh:mm
      for example:
         D 21:45
      which tells paKet to delay until 9:45pm before continuing.


   Practical exercise
      Modify FIRST.SCP to include these additional Script commands and run
      it again by typing <Alt-S>.

      Notice the delays and the effect they have on the screen display?











                               Page 246

Script Tutorial - the W and Q commands

   The D command is a fixed delay - it will always wait for that same
   period of time.  So if we used that method of separating our commands,
   we would find the Script taking more time than is really necessary,
   because most commands would not take the full 3 seconds to process.

   You could try a shorter delay to speed things up but sometimes we might
   need an even longer delay, for example if waiting for a response from
   another station.  A fixed delay just does not suit.

   There is a better way!   The "W" command will Wait for a period of
   time, looking for a particular string of characters.  So if we include
   the following line after sending a command:

         W 10,cmd:

   the Script will wait for up to 10 seconds, and while waiting it will
   be looking for the string "cmd:".  If the 10 second period expires
   before that string is received, paKet will continue processing from the
   next line in the Script.

   On the other hand, if that string ("cmd:" in this example) is detected,
   paKet will immediately cancel the wait, skip the next line in the
   Script and continue processing from the following line.

   Note the string you specify in the Wait command does not have to be a
   full line as received from the TNC.  paKet can match any part of the
   incoming data. So you could have:
      W 20,VK2DHU
   and the Wait would be satisfied if paKet receives:
      *** CONNECTED to VK2DHU

   When you write a Wait command, be sure to specify a time delay that is
   much longer than the time you would reasonably expect for the string to
   appear.  Processing will continue immediately the string is detected so
   in normal circumstances you will not have to wait for the entire period.

   In the example we are using here, we are waiting for the "cmd:" prompt
   to come up after we send a command to the TNC.  So a 10 second delay is
   more than enough, in fact we could make that 5 seconds and still be
   quite comfortable.  So, if the Script times out after that period,
   there must be something wrong.  When that situation arises, I generally
   want to abandon the Script and go look to see what caused the problem.

   The "Q" command tells paKet to Quit the Script.  This command has no
   parameters.

   So, let's modify our FIRST.SCP again to replace the 3 second Delay with
   a Wait and a Quit command, so it looks as follows:




                               Page 247

         B
         W 5,cmd:
         Q
         S MCON OFF
         W 5,cmd:
         Q
         S CONOK ON

   When we run this one, paKet will issue the Break command and wait for
   the TNC to respond with its "cmd:" prompt.  If that does not appear
   within 5 seconds, processing will drop down to the next line where the
   Q command will abort the Script.   If your TNC is one that does not
   produce a "cmd:" after the Break, you will wait for the full 5 seconds
   before the Script aborts!  In your case, remove the W and Q commands
   after the Break and go straight on to the first Send command.
   But in normal circumstances, the TNC will respond with its "cmd:"
   prompt and, with the Wait satisfied, the Script will immediately skip
   the Q command on the next line and continue processing our S command.
   Then it will wait again for another "cmd:", and so on...

   If you wanted to, you could add another Wait (and Quit) command after
   the last Send but that is not really necessary here in this example.


  Review:
   In this part:
      We introduced the W and Q commands.

   These commands:
      The W command is a selective Wait. There are two parameters here,
      separated by a comma.  We must specify a maximum time to wait (in
      seconds) as well as specifying the string to wait for.

      The Q command is a single letter command to Quit the Script.

   The syntax required:
      for the W command:
         W seconds,text
       eg:
         W 30,CONNECTED to
         W 120,messages waiting

      for the Q command:
         Q      (just a single character -
                 there are no other parameters required)

   Practical exercise
      Change FIRST.SCP again and replace the D command with the W and Q
      commands as shown.

      Run it again and watch how this Script is performed more quickly
      than the previous one.  You can see why the Wait command is to be
      preferred over the standard Delay command for this type of
      application.
                               Page 248

Script Tutorial - the G and : commands

   In modern Programming Schools, the humble GOTO statement is frowned
   upon.  But it is alive and well in paKet Scripts.  (As it is in DOS's
   BATCH facility)

   Usually paKet will move through the Script from beginning to end.  It
   starts with the first line, then moves to the second line, then the
   third etc until it reaches the last line of the Script.  A "G" (Goto)
   command allows us to vary that sequence, telling paKet we now want it
   to proceed from somewhere other than the next line in the Script.

   To use a Goto command we need to have a "Label" somewhere in the Script
   and in the Goto command we specify the name of that label. The Label is
   any line beginning with a colon (":").  Consider the following example:

         B
         :start
         S CONVERSE
         S This is my regular 15 minute Beacon message.
         B
         D 900
         G START

   In this example we have:
      - A Break command so we know we are starting in Command Mode.

      - The second line is a label because it begins with a colon.
        This line has no effect on the processing, it is just used as a
        marker for the G command we will come to shortly.

      - It sends a CONVERSE command to the TNC (we were in Command Mode
        don't forget) followed by a one-line message, before returning to
        Command Mode again with another Break code.

      - The Script will delay for 900 seconds (that is 15 minutes).

      - Then we come to a Goto command which tells the Script to adjust
        itself so its current line is the line where we wrote the ":start"
        label.  That means it will send another CONVERSE command etc etc
        and do it all again.

   This Script will go forever - there is no way out.  It is what
   programmers call a "loop".  Of course you can press <Esc> at any time
   to cancel a Script so you are still in control here.

   Note I used lower case when writing ":start" and upper case when writing
   "G START".  I did that deliberately to demonstrate paKet is not fussy
   about the case for the label.  If you spell it the same it will be OK.

   A label would usually be one word because that is how most programming
   languages use labels.  But here a label can be an entire line if you
   want.  You just have to ensure the Goto command specifies that full
   string if you want it to match.
                               Page 249


  Review:
   In this part:
      We introduced the G command and Labels (":").

   This commands:
      The G command is a Goto.  The Goto command must specify the label
      which identifies the point in the Script where processing is to
      continue.

      A Label is any line beginning with a colon (":").
      The label is simply used as a marker which may be specified in a
      Goto command.   paKet does no processing with a Label.

   The syntax required:
      for the G command:
         G text       (where "text" is a Label in this Script File)
       eg:
         G START
         G We are now connected

      for the Label:
         : text
       eg:
        : START
        : We are now connected    --- Note the leading blank is ignored so
        :WE ARE NOW CONNECTED     --- these labels are considered "equal"


   Practical exercise
      Create the Script as shown in this section, call it SECOND.SCP and
      store it in your Scripts directory.

      Feel free to change the "Beacon" text to anything that suits you and
      for testing you could reduce the 900 secs to 5 secs, just to make it
      quicker to test your Script when you run it.

      Watch your TNC switch from Command Mode to Converse Mode and back
      again after it sends the Beacon Text, and note the indicator
      "SCRIPT" is showing in the Status Window while the Script is running.

      Press <Esc> to cancel the Script when you want to stop it.












                               Page 250

Script Tutorial - the  * and E commands - documenting your Script

   You could used a Label as a comment in your Scripts.  As I mentioned
   above, a label has no effect on the processing so we can add several of
   these "labels" to our Scripts as a form of documentation. For example
   we could modify the example Script, SECOND.SCP, we were using here to
   look something like:

         : Let's start with a BREAK code to ensure we are in Command Mode
         B
         :--------------------------------------------------------------
         : The following line is the START label - the start of our loop
         :--------------------------------------------------------------
         :start
         :--------------------------------------------------------------
         : Set CONVERSE Command, send a message, return to Command Mode
         S CONVERSE
         S This is my regular 15 minute Beacon message.
         B
         :--------------------------------------------------------------
         : Delay for 900 seconds which is 15 minutes
         D 900
         :--------------------------------------------------------------
         : Now go back up to the "start" label to send another beacon
         G START

   Yes OK, I might have gone a bit overboard here with the comments, but if
   I had not explained the various commands or the concept of a loop, this
   Script might have seemed confusing to some people.  In Scripts and in
   conventional programming, I like to see plenty of comments.  If it is
   too difficult to easily explain in a comment, there is something wrong
   with your logic!  The addition of comments can make a Script more easily
   understood, especially if you send a copy of your Script to someone else.

   A paKet Script file is limited to 200 lines.  I decided to impose some
   limit to make it easier for paKet to manage the processing.  We can get
   around that limit by using the Call command which we will see a little
   later.  But I mention it here because each Script command line,
   including a Label, is counted as one line.   If you do happen to be
   writing a large Script and are approaching the 200 line limit, you
   should be aware of this and reduce the number of unnecessary "labels".

  * - a real comment.
   May I introduce the "*" command?   We didn't have this in earlier
   versions of paKet, but this one is a genuine comment - it's not really
   a command at all.  Although a Label does not actually DO anything, it
   still must be included in case we need it for a Goto command.

   But a comment line, that is any line beginning with an asterisk ("*"),
   is not counted as part of the Script when it is loaded into memory.  So
   you can have as many of these comment lines as you like without
   carrying any overhead in the Script.  Obviously this is to be preferred
   to using Labels for documenting your Scripts.

                               Page 251

   So, in the previous example it would be better if you replaced the
   colon (":") with an asterisk ("*") in every one of the Label/comments -
   except of course the REAL label, the ":start" label!

  E command
   Labels and comments are visible in the Script file when you edit or
   type the file, but while the Script is running they are not seen.

   The E command is documentation with a difference!   The E command will
   Echo to the screen all the text on this line, so you can use this as a
   form of documentation which is always seen by the paKet operator.  The
   information appears on the screen in the Communications Window as if it
   was received from the other station. It will also appear in your log
   file if it happens to be open at the time.

   This command could be used to:
      - inform the paKet operator of progress through various stages of
        processing as the Script is performed (especially if it is a
        complex Script taking some time to complete), or
      - it could be used to display some operator instructions at the
        beginning of the Script, or
      - it could be used simply to Jazz Up your Script to make it look
        more impressive.

   Let's have another look at our SECOND.SCP, this time with some
   different "documentation"...
         *********************************************************
         *                      SECOND.SCP                       *
         *                                                       *
         *  This Script will transmit a "Beacon" message every   *
         *  fifteen minutes.  The text of the Beacon is as shown *
         *  here in this Script.                                 *
         *                                                       *
         *  The 15 minute period may be changed by altering the  *
         *  D command to a different value.                      *
         *********************************************************
         *
         E Running Script file:  SECOND
         B
         :start
         *****************************************
         *   This part is done every 15 minutes  *
         *****************************************
         S CONVERSE
         S This is my regular 15 minute Beacon message.
         E
         E      +----------------------------------------------------+
         E      | Press <Esc> if you want to abort the Beacon Script |
         E      +----------------------------------------------------+
         E
         B
         *         Note - 900 seconds is the same as 15 minutes
         D 900
         G START
                               Page 252

   Here we see the comments using the asterisk now.  This is better than
   using Labels for comments because when the Script is loaded into memory
   for processing, these comment lines are ignored - they are not even
   loaded into memory with the rest of the Script.  Yet they remain in the
   Script file on disk so we have the benefit of that documentation
   without any overheads or limitations.

   The Echo lines will be displayed on the paKet screen as the Script is
   running.  I have added a couple of blank lines and a "box" around the
   message that is Echoed each time around the loop - just trying to be a
   bit fancy!

   I think this is sufficient to demonstrate the concepts of commenting
   your Scripts, both with the genuine comments and with Echo commands.
   It DOES make a difference, I think.

  Review:
   In this part:
      We introduced the E command and Comments ("*").

   These commands:
      The E command is a command to Echo text on the display while the
      Script is running.  The rest of the line is displayed as if it was
      received from the other station.

      A Comment is any line beginning with an asterisk ("*").
      Comment lines are not loaded into memory when running a Script so
      you can add as many Comments as you like to the Script File on disk
      without affecting the performance of the Script.

   The syntax required:
      for the E command:
         E text
       eg:
         E We are starting the SECOND Script File ...
         E The TNC should be back in Command Mode by now.


      for the Comments:
         * (text)       (The asterisk is required but text is optional)
       eg:
         * This Script was created by Tony Lonsdale on March 8th
         * The time delay could be increased if the frequency is busy.

   Practical exercise
      Edit our first Script file, FIRST.SCP, and add some comments plus an
      Echo command or two.

      Add a MYCALL command to send your callsign to the TNC.

      Run that Script again and observe the effect of the Echo commands.



                               Page 253

Script Tutorial - the C and R commands

   I mentioned earlier that a Script file is limited to 200 lines, not
   counting Comment lines.

   If you have a need for more than 200 lines, or if you have a more
   complex "application" you could structure your Script processing into
   modules, each of which may be up to 200 lines long.

   Then you can use the "C" command to call another Script.  Suppose we
   had three Script files, PART1.SCP, PART2.SCP and PART3.SCP and we
   wanted to run them all in sequence as one single task.  We could create
   another Script, let's call it MAIN.SCP as follows:

         E Beginning the 3 part series...
         C PART1
         E Part 1 completed
         C PART2
         E Part 2 completed
         C PART3
         E Part 3 completed

   In this example, we run the MAIN Script.  I have added a few Echo
   commands, to demonstrate its use in a more complex Script.  When MAIN
   is running the first thing it does (after the Echo) is to Call
   PART1.SCP.  paKet will load and run the PART1 Script file, then it will
   return to MAIN where it left off... this time dropping down to the next
   Echo then to another Call command which is the Call to PART2.  That one
   is loaded and run, and then back in MAIN, paKet will do PART3 before
   the MAIN Script is completed and control is returned to paKet's normal
   communications mode.

   So you can see we can overcome the 200 line limit by dividing our
   really long Scripts into two or more smaller ones and use the Call
   command to perform them all.

   There is no practical limit to the number of nested Scripts (depends on
   the amount of memory you have available).  So in our example, the PART1
   Script file could Call another Script, say PART1A. And that PART1A
   Script could call yet another one called ummm, PART1B. In every case,
   when a Script is completed it "Returns" to the one that called it, and
   if we are back to the highest level (or if we had only one level to
   start with), control returns to paKet.


  Return
   We have seen that when a Script is completed, that is when the last
   line has been processed and there is no more to do, that Script is
   terminated.   Control is returned to the calling Script if any, or to
   paKet.

   There may be times where we would like to "Return" before we reach the
   end of a Script.  The "R" command will do this for us.  Let me
   demonstrate with an example:
                               Page 254

         E
         E  **********************************************************
         E  *                This is the BBS Script                  *
         E  *      This Script establishes contact with the BBS.     *
         E  *                                                        *
         E  *         Once it has established that contact,          *
         E  *      it returns to paKet or to the calling Script.     *
         E  *                                                        *
         E  **********************************************************

         * Send a BREAK to the TNC to get into Command Mode
         B

         * Now, SEND a CONNECT command
         *  NOTE  change this Send command to use your own BBS's callsign
         S C VK2ATM-1

         * ... and wait up to 20 seconds for the TNC's CONNECTED message
         W 20,CONNECTED to
         G noanswer

         * We are now connected, so we can leave this Script now!
         R

         :noanswer
         E *** The BBS did not respond within 20 seconds ***
         Q

   I have inserted some blank lines in this example.  These, like the
   comment lines will be ignored when the Script is loaded into memory so
   if you think it makes your Script File easier to read with some
   additional spacing, feel free to add them to your Scripts.  It will not
   cost you anything, except in very rare circumstances it might take a
   little more disk space.

   This Script is using commands we have already covered.  So, if you are
   still reading this part of the Manual, you should be able to figure out
   what the Script is doing by now.  If you are not still reading, then
   ... uh no, we won't go into that!


   This Script might be called from another Script or we can call it up
   from the keyboard with the <Alt-S> command.

   In the example shown above I have a simple connection to my BBS so the
   20 seconds I allowed should be quite adequate there.  If your system
   requires a more complex connect path, you might need to make that
   somewhat longer.

   In this example, if we receive the usual acknowledgement within the 20
   second period, the Script will come down to the "R" command and
   terminate.   The job is done!

   So the R command allows us to return from any point in our Script.
                               Page 255


   Note the difference between a Return command and a Quit command which
   we use if the BBS does not respond.   A Quit is usually used when
   something is wrong and we just want to get out of here.  It will cause
   an error message to be displayed and the entire Script process will be
   aborted.  So if you are running in a nested Script, a Quit command will
   not only cancel that Script but any others that might have called it.
   You are back in paKet.   Unless there is a problem, a Return command is
   a tidier way out and is the preferred way of leaving a Script.



  Return Code
   The Return command can have an optional Return Code.  This could be
   used to indicate to the calling Script the results of a particular
   operation.  Let's have another look at the above example. Instead of
   the Quit at the end, we could issue a Return command with a return
   code.  For example:

         .
         .
         .
         :noanswer
         E *** The BBS did not respond within 20 seconds ***
         R 1

   The "R 1" will return to the calling Script just like any other Return
   command, but this one will also take with it a return code of 1.  If no
   return code is specified, paKet assumes a return code of 0.

   Then a calling Script could look at this return code and determine
   whether we are connected to the BBS or not.  If the code is 0 it knows
   everything is OK but if it is 1 it might decide to Quit or take some
   other action?

   At this stage, just keep in mind that you can add a return code to the
   Return command.  When we discuss Variables later, we will see how it is
   used in the calling Script.


  Review:
   In this part:
      We introduced the C and R commands.


   These commands:
      The C command will Call another paKet Script file.

      The name of the other Script is given on the Call command line.  If
      that Script is not in the normal Scripts directory, the Call command
      can specify full path details so the program can find that Script
      file.


                               Page 256

      The R command is Return command.

      When this command is performed in a Script, that Script is
      terminated and control is returned to the calling Script or to
      paKet, as appropriate.

   The syntax required:
      for the C command:
         C Script-file-name
       eg:
         C PART1
         C C:\TEMP\ONCEONLY.SSS

      for the R command:
         R return code     (The return code is optional)
       eg:
         R
         R 55


   Practical exercise
      Create a new Script, BBS.SCP, from the example given above.  Use
      the first example (with the Quit command) because we have not yet
      fully covered the handling of Return Codes.

      Test it by pressing <Alt-S> and establish contact with your BBS.
      Don't forget to change the callsign, and add any other path details
      required for your own BBS.  You might need more than 20 seconds too.

      This BBS Script will be used in the exercise for the following
      section.























                               Page 257

Script Tutorial - the AD, AU and AC commands

 File Transfers
   Here for the first time we see some two letter commands.  These are
   ASCII file transfer commands.  An ASCII file, by the way, is a file
   containing plain, printable text.

   "AD" is an ASCII Download command, and we must specify on the command
   line the name of the file we want to create.

   When this command is performed by the Script processing, paKet will open
   the file we nominate.  It works in a similar manner to the <F6> key so
   now everything received in this Stream will be written to that file.

   That file will be closed if we receive a <Ctrl-Z> code from the other
   station, but we can also close it with an "AC" Script command.

   If the named file is already present on our disk, paKet will not change
   that existing file but will create a new file with a different
   extension, starting with .000 but incrementing that number until it
   finds a filename that does not already exist!

   Once the file is opened and ready to receive data, processing continues
   from the next line in our Script.

   The "AU" command is an ASCII Upload command, and once again we must
   specify on the command line the name of the file we want to send.

   When this Script command is processed, paKet will open that file and
   send the entire contents of that file to the TNC.  When the last byte
   has been sent, the file is closed and paKet continues Script processing
   from the next line.

   What's this?  You want more examples?

   Hang on, I just want to mention the other type of file transfer -
   Binary File transfers.


  YD and YU commands
  ------------------
   These commands are the Binary File Transfer commands.  The name is
   taken from the original Packet Radio file transfer protocol, YAPP.  So
   these commands refer to "YAPP Download" and "YAPP Upload".  Of course
   paKet can use the advanced pP Protocol too and it will automatically
   select the advanced protocol if necessary. You don't have to worry
   about that - let paKet take care of it.

   A Binary File can be any type of file at all.  You can use these
   commands to send and receive plain ASCII text files if you wish, but
   they are more commonly used to transfer files which contain non
   printable codes; files such as programs (.COM and .EXE files) or any
   archived file (eg: files with .LZH or .ZIP extension).

                               Page 258

   The use of these commands is very similar to the ASCII file transfer
   commands.  The process is also covered fully in the Windows section of
   this Manual - see the part on the Binary File Transfer Window.  Also
   have a look at <F7> and <F8> in the Keyboard Commands section of this
   Manual.

   If you want to send a Binary File you must specify the file name on the
   "YU" command line.   When receiving a Binary File, the "YD" command
   alone is quite sufficient because the other station will include the
   filename in the Protocol Header.

   OK, OK... those examples.

   Here is a Script to call the BBS and List all unread messages,
   capturing those details into a file on our disk. Conveniently, it will
   Call the BBS Script we created earlier to establish connection with the
   BBS so we won't have to go into all that detail here.

         ************************************************
         *                 BBSLIST.SCP
         *
         *  This Script will connect to the BBS, List
         *  all unread messages and Bulletins, storing
         *  all that data in a file named BBSLIST.DAT
         *  on our hard disk.
         ************************************************
         C BBS
         *
         * The BBS Script will Quit if the connection is not established
         * so if it comes back here we must be connected now!
         *

         * Open a file to capture the BBS message list
         AD C:\PAKET\BBSLIST.DAT
         E The text file is now open and ready to receive data...

         * Ask the BBS to "List" the last 10 messages in its Mailbox
         S LL 10

         *
         * OK, that's done, now we can close our data file
         *
         AC
         * and disconnect from the BBS
         B
         S D
         R

   That looks easy enough.  But when we run it, we find there are no
   message details in our new data file, even though we might have seen
   them on the screen as they were received from the BBS!   What went
   wrong?   Can you figure it out?  This is called "debugging" and this
   aspect of programming can be the most frustrating part of it.

                               Page 259

   Yes, "programming".  Whether you knew it or not, you are now a computer
   programmer.  Writing a program means to develop a series of
   instructions for the computer to follow.  That is exactly what we are
   doing here.

   Anyway, now that we have something in common, let's investigate the
   problem we have with this program... er, I mean Script.  What is
   happening here?

   No, come to think of it, I might leave you to have a go at debugging
   that one yourself.  I'll come back to it later.  We'll make that part
   of your Practical exercise for this section.

  Review:
   In this part:
      We introduced the AD, AC and AU commands.
      We also covered the YD and YU commands.

   These commands:
      The AD command ("ASCII Download") will open a text file on disk and
      will write all incoming data to that file until it is closed.

      The AC command ("ASCII Close") will close the file we opened with
      the AD command.

      The AU command ("ASCII Upload") will send the contents of the
      specified text file to the TNC.

      The YD command is the Binary File Transfer Download command, which
      is used to transfer a Binary File FROM the other station.

      No parameters are required here because the other station will
      include those details with the file header, and paKet will know what
      to do with it.  Before issuing the YD command in your Script you
      should make sure the other station is ready to transmit in YAPP or
      pP mode.  This usually involves sending some sort of command to the
      other station, such as the BBS's "YD" command to tell it we want it
      to send one of its files to us.

      The YU command is the Binary File Transfer Upload command, which is
      used to transfer a Binary File TO the other station.

      We must tell paKet which file we want to send on the YU command
      line.  Again we should ensure we have issued the appropriate
      commands to the other station to prepare it to receive our file
      before we issue this YU command in our Script.

    The syntax required:
      for the AD command:
         AD New-file-name
       eg:
         AD MSGS.DAT
         AD D:\TEMP

                               Page 260

      for the AC command:
         AC      (there are no parameters required)

      for the AU command:
         AU file-name
       eg:
         AU CMDS.DAT
         AU C:\PAKET\PREPARED.MSG

      for the YD command:
         YD      (there are no parameters required)

      for the YU command:
         YU file-name
       eg:
         YU PAKET.EXE
         YU C:\GOODIES\FRED.LZH


   Practical exercise
      Create the BBSLIST.SCP from the example given above. This calls the
      BBS.SCP we discussed in the previous section so it will be easier to
      do this exercise if you have done that one and got it working.

      Load and run this BBSLIST Script, watching the Screen closely as it
      runs.  If you have successfully Called the BBS Script file, you will
      see the Connect command appear on your screen.  If it aborts you
      will get a message pop up - in that case you will have to try to
      find out why it aborted.  Is everything typed correctly, exactly as
      shown here?  Have you made any changes - if so they must be checked
      carefully.  Maybe the problem is simply the BBS did not have time to
      respond within the time you have allowed? (That's easy to fix!)

      Assuming you do get a successful connection and the BBS sent back
      some message details in response to our List command, it should all
      be in the BBSLIST.DAT data file we specified with our AD command.

      If it is not there, we have to find out what went wrong.  We have to
      go back over the Script commands, examining each one carefully and
      try to "play computer", that is to imagine WE are the computer,
      religiously and blindly following each and every instruction.

      It might take a little experience but I am sure you will soon spot
      the problem here.  We have told the system to send a List command to
      the BBS.  Fine, it does that.  Then it drops down to the next
      command which closes the file!  Already!  Hey, the BBS is still
      looking for those messages and we have closed the file already!  We
      need some sort of Delay, preferably a Wait in here so we do not
      close the file until AFTER we get those message details.

      See if you can work out what to do here, but I'll give you a hint.
      I would insert a Wait command after sending the LL 10.


                               Page 261

Script Tutorial - the ! command

   Wouldn't it be nice if we could run some DOS commands from within paKet?

   Oh, I thought you would never ask...

   The "!" command can be used in a Script to do just that.  With this
   command paKet will pass over to DOS whatever you place on this Script
   line.  So if you have:

         ! COPY C:\PAKET\BIN\UPLOAD\*.LZH A:\

   paKet will send that COPY command to DOS for processing.  There are no
   limitations on the type of command you can run here.  If you can run it
   at the keyboard from the <F9> DOS Gateway, then you can run it here
   from the Script.  The paKet program is still in memory of course so it
   is taking up a lot of precious memory.  Hopefully there is enough left
   to run your DOS command?  It might be an internal DOS command such as
   this COPY command or DIR, etc.  It could be a program such as:

         ! C:\DOS\MEM /C > D:MEM.LST

   although in that case you do not even need to specify the "C:\DOS\"
   if DOS can find that MEM program in its PATH.

   Or you can use a DOS batch file.  So if you had a batch file called
   say, HOUSEKEP.BAT available in the current directory or within the DOS
   PATH, you could have:

         ! HOUSEKEP

   If the Script command line contains just the "!" command without any
   parameters, paKet will call up DOS and leave you with the DOS prompt -
   just like pressing <F9>.

   I decided to avoid any pause after this DOS command is performed.  I
   could have added some sort of pause where you have to press a key or
   something like that to give you time to peruse the results of this DOS
   operation.  However, that tends to defeat the purpose of automating the
   process in a Script!  So when the DOS command is processed and control
   returns to paKet's Script, everything proceeds without any delay.  This
   means you will not have time to look at the DOS screen to see what
   happened.  If you want to see that screen I suggest you make up a DOS
   Batch file with a PAUSE command and specify that Batch file here as
   your Script command.

   You should keep in mind that a REMOTE user will have access to any
   Script file in your Scripts directory, if it has the standard .SCP
   extension.  So if you have a Script to do some significant DOS
   processing, such as erasing files from your disk, or even to ...
   (shudder) ... to format your disk, you might need to keep that Script
   out of the Scripts directory or perhaps to rename its extension to
   something other than SCP.  That way, you will not risk having some
   (perhaps innocent) REMOTE user Perform that Script without your approval.
                               Page 262


  Review:
   In this part:
      We introduced the ! command.

   This command:
      The ! command is a Script command to execute a DOS program,
      including a BATch file or an internal DOS command.

   The syntax required:
      ! (DOS-program-name/command)    (The parameter is optional)
    eg:
      ! LHA M C:\PAKET\SAVELOG C:\PAKET\*.LOG
      ! SCANDISK
      !

   Practical Exercise:
      I am sure it won't take too much imagination on your part to come
      up with all sorts of things you could do with this command.  But
      just for the simple exercise, make up a Script with just one DOS
      command: display the contents of your CONFIG.SYS file on the screen.
      If you use the DOS "TYPE" command it will appear briefly then
      quickly disappear as control returns to paKet.  If you have the LIST
      program handy, use that.

      Yes, I know this is a trivial example, but it is pretty harmless
      too!   Here, let me illustrate:

         ! LIST C:\CONFIG.SYS

                or

         ! TYPE C:\CONFIG.SYS




    ------------------------------------------------------------------
    At this stage I consider we have covered enough about Scripts for you
    to be able to make effective use of the Script system in paKet.

    With the commands we have covered I think you could achieve quite a
    lot of automation in your daily operations.


    The rest of this section of the Manual contains more information on
    Scripts and introduces some more sophisticated commands and techniques.

    By all means read on, and explore the power and creativity that lies
    in the use of these more powerful commands.  But if you are having
    trouble keeping up, you might like to get some practice with the
    commands we have covered so far, and get into the heavy stuff later.
    ------------------------------------------------------------------

                               Page 263

Script Tutorial - the T command

   A Wait command will wait for a time, looking for a particular string of
   characters.  This is most useful if that is the only string we are
   interested in at the time.  A good example of this is the TNC's "cmd:"
   prompt.  If we issue a command and want to know when the TNC is ready
   to take another one, the "cmd:" is the only string we need to look
   for.  Anything else is not really relevant to our needs at the moment,
   so we can wait for that string and ignore everything else.

   But things are not always so precise and convenient.  Sometimes there
   may be several possibilities and we cannot be sure which string will
   come first, or even IF a particular string will come in at all!

   This is where the Trap command ("T") can be useful.

   Trap is a Script facility where we can specify up to 30 different
   strings to watch out for, each of which has a Label to identify the
   Script code we want to perform if THAT particular string is detected.

   Perhaps the best way to illustrate the concept of Traps is to give you
   a working example. For your Practical Exercise for this section, make
   up a Script as follows:

         T The BBS,VK2ATM
         T pgm,paKet
         T My friend,Andy

         E We are starting the Trap Script to look for
         E some things while we monitor the frequency.

         :top
         D 60
         E We are still in the Trap Script
         G top

         * The following Script commands are used only if a Trap occurs
         :The BBS
         E We have spotted some BBS activity
         G top
         :pgm
         E Somebody is using paKet around here
         G top
         :My friend
         E Oh, there's my mate Andy!
         G top

   This Script starts with three Trap commands.  I suggest you change the
   text following the comma on these commands to something you are likely
   to see when monitoring the frequency on your system.

   In the example shown above the first Trap is looking for the callsign
   of my local BBS (VK2ATM in my example).  If that string is detected,
   paKet will perform a Goto to the ":The BBS" Label.
                               Page 264


   The second Trap command is looking for the word "paKet"; the third
   command is looking for the string "Andy".

   So when I run that Script here, paKet makes a note of these three
   Traps, then after a couple of Echoes it begins a 60 second delay.
   During this time anything that is received over the air will be
   processed and displayed on the screen.  When the 60 second period
   expires, we get the message "We are still in the Trap Script" then we
   go back for another 60 second delay.  We get that message every 60
   seconds just to remind us what we are doing!

   If, while we are monitoring and displaying incoming data, we receive
   one of the Trap strings (eg: "paKet") the Script will jump down to the
   Label specified for that string.  In this example we would go to the
   :pgm Label and continue processing the Script from there.

   You can see that will Echo a message about paKet the go back for
   another turn around the Delay loop.   You can do whatever processing
   you like there - I am just Echoing a message to keep it simple. The
   important thing here is to see how the Traps operate.

   And if the word "Andy" appears anywhere in the monitored data, it will
   echo a message about my mate Andy before going back around the delay
   loop.

   If none of these Trap strings is received, it will just go on repeating
   the "We are still in the Trap Script" message every 60 seconds.

   Press <Esc> to cancel this Script.


   Another (more complicated) example?

   Suppose our BBS produces the message "You have mail waiting" if there
   happens to be some new mail in its Mailbox that we have not yet read.

   We could modify our BBSLIST Script File to include the following Trap
   command:

         T mail, You have mail waiting

   This new command tells paKet to watch out for the "You have mail
   waiting" string and if it is detected, the Script processing is to
   continue from the ":mail" Label.

   Our BBSLIST Script might look something like this:







                               Page 265

         ************************************************
         *                 BBSLIST.SCP
         ************************************************
         T mail, You have mail waiting
         C BBS
         AD C:\PAKET\BBSLIST.DAT
         E The text file is now open and ready to receive BBS data...

         * We know the TNC has connected, but we should wait for
         * the normal BBS prompt which includes the "X,Y,Z etc"
         :wait
         W 60, X,Y,Z,?) >
         Q

         * When the BBS is ready, THEN send our command
         :list
         S LL 10

         * Then wait for the listing to finish before closing our file
         W 120, X,Y,Z,?) >
         Q
         AC
         B
         S D
         R

         :mail
         * We come here ONLY IF the Trap detects the Mail Waiting string
         * Which would be sent while we were waiting for the first BBS prompt
         W 120, X,Y,Z,?) >
         Q
         S RM
         G wait

   It is just as well you are now becoming familiar with Scripts because
   this one is looking a bit complicated now.  But take it steadily, one
   command at a time and I am sure you will cope with this OK.  It is
   basically the same as the previous BBSLIST Script with the addition of
   the Trap command at the top and the ":mail" routine at the bottom.

   I have removed some of the spacing and comments because it is becoming
   a bit big to be repeating all that here in this section when you can
   easily go back a few pages to see the earlier copy.

   Oh... it looks like I have also added those Waits we were talking about
   earlier.  Remember that bug we had?   Oh well, you have seen it now so
   it's too late to cover it up.  We might as well talk about it then...

   I added a Wait for 60 seconds at first just to wait for the BBS prompt.
   The other Script we called (BBS.SCP) returns as soon as it sees the
   TNC's Connected message.  So I added a Wait to give the BBS time to
   come up with its first prompt before sending the "LL 10".


                               Page 266

   Then after sending the "LL 10" another Wait - this time I waited for up
   to 2 minutes to get the next prompt.  The BBS will send another prompt
   AFTER it has sent the Listing we requested (I hope 2 minutes is
   sufficient time).  Then we can close the file.

   In case you are wondering about that funny string "X,Y,Z,?) >", I
   should explain that is just the end of the usual BBS prompt string.
   Yes I know I could have specified the entire prompt string but I
   figured that much was rather unique and should be more than enough to
   properly identify the string I was looking for.

   Anyway, back to the Trap:

   When our new Script runs, it processes the Trap command first.  That
   tells paKet to record those details and to maintain a watch for that
   string.

   My local BBS might come up with that Mail Waiting message as soon as I
   connect so it would be received before I get the first Menu Prompt.
   That means if we are going to get that string at all, it would come in
   during our 60 second Wait.

   If we do not happen to have any mail waiting, the BBS will not send
   that message.  So our Script will perform exactly the same as if we had
   not bothered about the Trap at all.  It simply sends the "LL 10", waits
   for another prompt, closes the ASCII file and Disconnects.  So, if the
   Mail Waiting string does not come in, our new ":mail" routine is not
   used at all!

   But, suppose we did have some mail waiting and the BBS did send us that
   message after we make the connection.... let's follow the logic flow as
   we run this Script:
      1. The Trap command is recorded.  That's all that is done at this
         stage.  paKet simply records both the String we are looking for
         and the Label we want to associate with that string.  No other
         action is taken.

      2. we call BBS.SCP to make the connection.  That will Quit if we
         fail to make the connection, so if control returns to our BBSLIST
         Script, we know the TNC is now connected.

      3. The AD command opens our data file and the Echo command sends a
         confirmation to the screen.

      4. We begin a 60 second Wait now, looking for the BBS prompt.  As
         soon as that is received, we will drop down to the Send command
         where "LL 10" is sent to the TNC.

      5. But in this particular case, the BBS sends us the "You have mail
         waiting" string while we are waiting for its first prompt.

      6. The Trap processing detects this and switches control over to the
         ":mail" label.

                               Page 267

      7. Here (in the :mail routine) we continue to wait for that first
         prompt, just to keep things tidy.  When we get the prompt we
         issue a BBS command to read our mail (that is what the RM is
         for).

         Then it can go back up to the ":wait" label because there it will
         wait for another BBS prompt.  The BBS will send us another
         prompt when it has finished sending our mail.

      8. Now that we have our mail, and the BBS has sent its next prompt,
         telling us it is waiting for another command, we can drop down to
         the List command and we continue our normal processing from
         there, eventually closing the data file and disconnecting from
         the BBS.


   Yes, it does look rather complicated at first glance, but you can see
   that if you take each command in turn and follow the logic through,
   step by step, it does make sense.  And as you gain more experience with
   Scripts you will be able to read that sort of thing as easily as you
   read the morning newspaper.   Promise!

































                               Page 268

Script Tutorial - the FC, FS and FT commands

   These commands are the Script Flag commands.  There are three of these
   commands and each requires a parameter, a number between 0 and 9:

      FC n     Flag Clear
      FS n     Flag Set
      FT n     Flag Test.

   A "Flag" is simply an indicator we can set (or clear) during the Script
   to remind us of some condition or circumstance, and that flag can be
   tested later in that Script.   There are 10 Flags available, 0 to 9.

   This facility was created in paKet 5 and is included in this version
   for compatibility with existing Scripts.  Now that we have Variables in
   paKet 6 (yes, yes I am coming to Variables) you could use them to do
   the same job.   Anyway, Flags are here so I'll show you how to use
   them.


   If we come to some condition we need to know about later we can set a
   Flag, for example:

         FS 6

   This sets Flag number 6.  By the way all Flags are presumed to be Clear
   (i.e. NOT Set) before a Script starts.

   You can Clear a Flag with the Flag Clear (FC) command.

   Then, later in our processing we can test this Flag to see which way we
   want to go.   The Flag Test (FT) command will look at the Flag we
   nominate here and if the Flag is set, the next Script line is
   performed.  But if that Flag is Clear, paKet skips the next line in the
   Script and continues from the line after that.  Let's have another
   example:

         .
         .
         FT 6
         G Gotcha
         E The Flag was not set
         .
         .
         .
         : Gotcha
         E The flag was set...
         FC 6
         E ... but is now cleared again
         .
         .



                               Page 269

Script Tutorial - Variables

   I'll bet you thought we would never get to Variables!

   What is a Variable anyway?

   In its simplest terms, a Variable is a small piece of the computer's
   memory that we can use in our Script, to store some temporary
   information.  It may contain varying values because we choose what goes
   into it!

   Each of these Variables is identified by a unique name.  There are 36
   Variables altogether, 26 ordinary Variables and 10 special Variables
   which I will call "Passed-Parameters".

   The 26 ordinary Variables are identified by the letters of the alphabet
   and the syntax we must use is to specify a Variable with a Percent sign
   followed by a single letter, eg:
         %A  (or %a  - same Variable)
         %J
         %Z

   The Passed-Parameters are similar but they use numbers from 0 to 9, eg:
         %0
         %5
         %9

   How are variables used?  Perhaps the easiest way to demonstrate is to
   introduce a new command:

Script Tutorial - the M command

   The Move command moves some data into a Variable.  The syntax required
   is:
         M variable,data

   For example:
         M %A,VK2DHU
         M %b,Tony
         M %K,99

   All Variables contain text data so that one with 99 actually contains
   two ASCII characters, not a single numeric value of 99!



   You may use Variables in any of the Script text strings.  So we could
   have, for example:

         T exit,%B is not home
         E Connecting to %A...
         S CONNECT %A
         W 10, Connected to %A

                               Page 270

   These commands would be interpreted as follows (assuming the above Move
   commands have been performed earlier in this Script):

         T exit,Tony is not home
         E Connecting to VK2DHU...
         S CONNECT VK2DHU
         W 10, Connected to VK2DHU

   You can choose any of the 26 Variables for any use you wish.  There is
   just one thing I need to mention.  The %Z variable is used by the
   Script system to carry the Return Code from a "Called" Script.

   The Return Code.   Don't tell you've forgotten that already?

   Alright, let's have another quick look at the Return command. We might
   usually specify just the single letter "R" to return from a Called
   Script, but if we wanted to return the result of some operation, we
   could give it a Return Code by writing something like "R 50".

   If we did that, the %Z variable would now contain a value of 50.

   Let's have a look at that again with an example:
         E Testing the Return Code
         C SUBS
         E *** The return code from Subs is %Z ***

   So if the SUBS Script finished with:
         R 9
   then the last line of our Example would Echo on our screen:
         *** The return code from Subs is 9 ***

   You can use the %Z Variable for any purpose at all, but remember it
   might be overwritten by the system if you Call another Script!


Script Tutorial - Passed-Parameters

   These are the ten numeric Variables, %0 to %9.

   When we Call another Script, we have an option to include on the
   Call command line some additional information, which will be passed to
   the Called Script. If we have the following line in our MAIN Script:
         C SUBS,Tony

   Then the SUBS Script knows what parameter was specified because it is
   stored in %1 (it is the first parameter on the line).

   If the SUBS Script included something like:
         E SUBS Script parameter number 1 contains %1

   you get no prizes for guessing that will Echo on our screen:
         SUBS Script parameter number 1 contains Tony


                               Page 271

   Each of the parameters on the Call command line are allocated to the
   Passed-Parameters Variables in the Called Script in the same sequence
   they are written.  The first parameter goes into %1, the second into %2
   and so on.

   You might see why the numeric Variables are called Passed-Parameters.
   In the example above I had only one parameter ("Tony") but you can have
   up to nine of them, separated by commas.  If we had this Call command:

         C SUBS,Tony,VK2DHU,Port Macquarie,Australia

   then the Variables %1, %2, %3 and %4 would be filled and accessible
   from within the SUBS Script.  For example, %3 would contain the string
   "Port Macquarie".

   If you are observant, you will have noticed we are unable to include a
   comma as part of a parameter because it is used as a delimiter to
   separate the parameters.  Yeah, OK you got me there!  Sorry about that,
   but it is true.  You can't have a comma in a parameter!  Maybe in paKet
   version 97.2?

   While I am dealing with you observant ones, why do we have ten
   Passed-Parameters and only nine available on the command line?
   Time's up!   The first one, %0, always contains the name of the Script
   file currently running.  It doesn't matter whether we are using Called
   Scripts or not, you can always specify %0 in any Script and it will
   contain the name of THIS Script that is currently running.



























                               Page 272

Script Tutorial - Scope of Variables

   The ordinary Variables are considered Global in scope which means you
   can set a Variable in one Script and use that same variable in another
   Script in this run.   For example, if we have a MAIN Script as follows:

         M %A,Australia
         E We start with %A
         C SUBS
         E Back again and our variable now contains %A.
         .

   and our SUBS Script looks like:

         E In SUBS now... and A still has %A
         M %A,UK
         R

   When we run the MAIN Script, we will see the following Echoes on our
   screen:

         We start with Australia
         In SUBS now... and A still has Australia
         Back again and our variable now contains UK.



   The Passed-Parameters are different.  They are considered local and are
   not visible to other Scripts.  So %1 in the main Script will probably
   contain a different value to the %1 in a called Script.
























                               Page 273

Script Tutorial - a breather...

   Whew!

   How's it going?

   If you have had some programming experience you might be finding this a
   bit easier than if you are new to computers.  But don't despair if you
   are finding this a bit heavy.  You can get a lot out of Scripts by
   using some of the simpler commands we covered early in this section of
   the Manual.

   The Called Scripts, the Variables, and other complexities can wait...
   or you can still make use of some "clever" Scripts written by someone
   else.


   But if you are still with me... there's more.  Oh yes, we're not
   finished with Scripts yet.



































                               Page 274

Script Tutorial - the I command

   Wouldn't it be nice if we could get the Script to stop and allow us to
   enter some information at the time of RUNNING the Script, instead of
   having to edit the Script File every time we want to run it?

   Didn't I tell you about this one?  This is the Input command.

   There are two parameters to this command.  The syntax is:
         I variable,prompt_string

   For example:

         I %C,Enter the callsign of the station you want to call...

    when the Script comes to this command, a Message Window will pop up
    displaying our prompt:

         Enter the callsign of the station you want to call...

    and paKet will stop while you enter something on the input line.
    Press <Enter> to complete your data.  Whatever you typed (except the
    <Enter> - that is not included) will now be stored in that variable,
    %C in our example here.  The Script then continues from the next line.



Script Tutorial - the ? and J commands

   The "?" is a Query command and is used to compare two values.

   In most formal programming languages, there is an IF statement which
   might look something like "IF A > 99 THEN Do-something".  I would have
   liked to provide some better way to compare two values, but this "?"
   command is the best I could do in the time available.  Hey, this is
   just a Communications Program after all!

   Anyway, the Query command is used with similar syntax to the other
   Script commands:
         ? value1,value2

   For example:
         ? %A,Port Macquarie
         ? %Z, %2
         ? Paul,Tony      (Don't ask me why you would want to do this,
                           but at least the syntax is valid!)

   The comparison is a text comparison and once again it is not sensitive
   to the case.  So "Tony" and "tony" are considered equal. And "90" is
   higher than "100".   Eh?  90 is higher than 100?   Yep, when doing a
   text comparison it finds the first character, "9" higher than the "1"
   so it decides 90 is higher than 100!


                               Page 275

   Performing a Query command is only half the job.  We also need some way
   of acting on the result of that comparison.  So we have a Jump ("J")
   command.  Actually we have six Jump commands:

         JE    Jump if the two values are Equal
         JNE   Jump if the two values are Not Equal
         JL    Jump if the first value is Lower than the second
         JNL   Jump if the first value is Not Lower than the second
         JG    Jump if the first value is Greater than the second
         JNG   Jump if the first value is Not Greater than the second

   The Jump commands have one parameter, that is the Label we want to Jump
   to if that condition is satisfied.  So we could have:
         C SUBS
         ? %Z,0
         JE Success
         ? %z,5
         JG Big Score
         JE five
         .
         .
         :Success
         E The SUBS went OK because we got a zero return code
         .
         .
         :Big Score
         E SUBS returned a value over 5!
         .
         .
         :five
         E We got exactly 5 in the SUBS return code
         .
         .


   The Jump commands will act on the LAST Query to be performed.  It would
   be the norm to issue a "?" command immediately prior to the Jump.  But
   if you forget to do the Query, paKet is quite happy to continue.  It
   will use the result of the last Query you did, no matter how long ago
   that was.  If there have been no Queries at all in this Script, paKet
   will consider the "result" to be Equal!













                               Page 276

Script Tutorial - the L, P and X commands

   I almost forgot these.

   But these simple commands are so simple it won't take long to explain
   them ALL!

   They are all single letter commands - no parameters on any of them.


   The L command toggles the Disk Log file on or off.  If it was on, this
   command will turn it off;  if it was off, this command will turn it on
   (using the default Log File name).

   The P command toggles the Printer Log on or off.  If it was on, this
   comm... (yes, yes, alright.  I know you know!)

   The X command is different and one that I sometimes think you should
   not have at all.  But someone asked for it, so it is still here.  This
   one will exit the paKet system altogether, returning us to the DOS
   Operating System (or to Windows or OS/2 or wherever we came from).  It
   is even more drastic than the <Alt-X>  (or the <Alt-F4>) command.  At
   least with those, you are asked "Are you sure?".  The X command does
   not give you a second chance.  So please use this one only if you are
   really sure you need it.











   Well, that's it!   Now we have covered all the Script commands.
   And now it's over to you to see what you can do with it all.  Try some
   simple ones to start with and build on them.  Discuss them with other
   paKet users on air and swap those you are satisfied with.  We can
   always learn from each other.

   I would be interested to hear of any ideas you have and to see the
   fruits of your Scripting labours.










                               Page 277

The Script File syntax.

  The rules:-

      1. The Script file is plain ASCII text
         (Extended ASCII graphic characters > $128 allowed).

      2. All lines must be less than 80 characters.

      3. Each Script file is limited to a maximum of 200 lines.
         (Use the CALL command to CALL other Scripts if you need more).

 All spaces will be ignored, except for EMBEDDED spaces in "text strings"
 (eg: in the Send command - LEADING spaces in "text" will be ignored). For
 example:

      s YU PROG.EXE
      W 10, Ready to Receive with YAPP protocol
      g not ready
      y u prog.exe

 is identical to:

      SYU PROG.EXE
      W10,Ready to Receive with YAPP protocol
      GNOT READY
      YUPROG.EXE


 You are the "programmer" here so choose a style that suits you best.
 Most people would find the latter example more difficult to read.  The
 careful use of spaces makes for more easily understood programming, which
 probably means fewer logic problems in your Scripts.





















                               Page 278

Script Command Summary

   The following Script commands are valid:

   ! dos_command      Run a DOS command.
                      This will load a copy of COMMAND.COM and will pass
                      'dos_command' to DOS for processing. When that DOS
                      command/program has finished, processing of the
                      Script will continue from the next line in the
                      Script.

                      The comments I made for the <F9> key and for the
                      <Alt-E> in the "Keyboard Commands" section of this
                      Manual apply here too. You will not have the usual
                      amount of memory available for these DOS commands
                      because paKet is still running and still occupying a
                      lot of memory.


   *                  This is a comment line if it begins with an "*".
                      The rest of the line may contain anything at all
                      because a comment line is not loaded by the Script
                      processing.  It is used entirely as documentation in
                      your Script File on disk.

                      I strongly recommend the generous use of comments
                      in your Scripts.  If nothing else, writing comments
                      helps you to focus your mind on your own logic.


   : label            No processing is performed on this line.
                      It is used by the Goto, Trap and Jump commands.

                      As no processing is performed here, this could also
                      be used as a comment in your Script file.  But in
                      this case it IS loaded into memory with your Script.
                      If you intend this to be a comment only and not a
                      Label, it would be better to use the "*".

                      "label" may be any length but the total line length
                      must be less than 80 chars.

   ? value1,value2    Query command to compare two values.
                      This command compares the contents of the first
                      value with the contents of the second value.
                      The value fields may be Variables or constants.

                      This comparison is used together with one or more
                      Jump commands to provide some decision making
                      capability in a paKet Script.




                               Page 279

   AC                 Close the Download file.
                      Presumably this will follow the AD command somewhere
                      in your Script?

                      If the file is already closed, this command will be
                      ignored.

   AD filename        ASCII File download
                      (Same as <F6> but you must put filename on the
                      Script command line. (Eg: AD RECVFILE.DAT)  Note
                      that like <F6> if the file already exists, a new one
                      will be created with a sequential numeric extension
                      (RECVFILE.000 or RECVFILE.001 etc).


   AU filename        ASCII file Upload.
                      Same as <F5> but again you specify the filename in
                      the Script command line. (Eg: AU SENDFILE.DAT).


   B                  Send a BREAK code to the Serial Port. (Same as
                      <Alt-B> - return to cmd: mode)


   C script,p1,p2,... Call another Script, with optional parameters.
                      A Script file is limited to a maximum of 200 lines,
                      but if you find this limiting your style, you can
                      set up a number of Scripts and Call them as
                      required.

                      There is no practical limit to the number of nested
                      Scripts you may call. Each of the called Scripts
                      should "Return" to the calling Script, where
                      processing continues from the line following the
                      Call command.

                      Note the facility for Variables, Return Codes and
                      Flags to return the status of important events while
                      in the called Script.

                      If you want to pass some parameters to the called
                      Script, those parameters may be entered on the
                      command line.  The parameters are separated by a
                      comma.  Up to nine parameters may be specified.


   D time             Delay for "time" seconds, or delay until hh:mm.
     or               "time" may be 1 to 32767 seconds (about 9 hours).
   D hh:mm            "hh:mm" is a time of day.

                      If this time-of-day format is used, paKet will wait
                      until that time occurs before continuing.  Note, if
                      this time is earlier than the current time, paKet
                      will wait until that time TOMORROW before continuing.
                               Page 280


   E text             Echo text to the screen.
                      This is included mainly as a form of documentation
                      within the Script. The text is echoed to the screen
                      as if it was received from the other station, so it
                      will appear in your log file if it is active.


   FC n               Flag Clear
   FS n               Flag Set
   FT n               Flag Test
                      There are 10 flags available within the Script
                      system.

                      These are Binary flags (i.e either ON or OFF)
                      numbered 0 through to 9 and may be used by the
                      Script Programmer (that's YOU).

                      It was found by a paKet/Script user that there are
                      times when you need to remember the status of some
                      condition during the Script process.  By setting one
                      (or more) of the flags you can test the status of
                      that flag later in the Script and adjust the
                      processing as required.

                      For example you might need to note the fact that a
                      particular string was received from the TNC (using
                      the "W" command). When that string was received you
                      could Set a flag with the Flag Set Command,
                      (eg) "FS 4".

                      Later during this Script you could check the status
                      of that flag with the Flag Test command (eg) "FT 4".
                      If the flag is set, the next Script command is
                      performed, but if the tested flag is not Set (or
                      Clear) the next line in the Script is skipped.

                      With the introduction of Variables in paKet 6, we
                      have an alternative.  Instead of using a Flag, we
                      could Move some value into a Variable and Query that
                      Variable later.

                      You are the programmer, you make your choice!


   G label            Goto "label" and continue the Script from there.
                      (Yeah, yeah I know Goto is unfashionable!)


   I var,prompt       Input a string into a Variable.
                      paKet will display the prompt string in a Message
                      Window while waiting for you to enter some data
                      which will be stored in the specified Variable.

                               Page 281

Script Command Summary (cont)

   JE  label          These Jump commands will Jump to the Label specified
   JNE label          here, depending on the result of the previous Query
   JL  label          ("?" command).
   JNL label
   JG  label
   JNG label


   L                  Disk Log File On/Off toggle
                      This uses the default log filename.


   M var,text         Move data into a Variable.
                      The data is always taken as ASCII text data, even if
                      numeric strings are entered.


   P                  Printer Log On/Off toggle.


   Q                  Quit.
                      The Script processing is terminated. This would be
                      used for an aborted exit.

                      If we are using nested Scripts and the Quit is
                      performed in a Called Script, the entire chain is
                      aborted and control returns directly to paKet.

                      The Return command is a tidier way to exit a Script.


   R (return code)    Return with an optional Return Code.
                      This command is especially used to return control to
                      a calling Script. If used in the first level, or
                      only Script, Script processing is terminated and
                      control is returned to paKet.

                      The optional Return Code can be used to send back
                      results of this Script.

                      A Return will be assumed at the end of a Script file.


   S text             Send "text" to the TNC.
                      If you want to include a Control character such as
                      <Ctrl-C>, or an <Alt- > key combination such as
                      <Alt-A>, refer to the Special Key Codes section of
                      this Manual for the special syntax. Do not enter
                      quotes unless you want them sent to the TNC.



                               Page 282

                      You can also use substitution parameters such as $t
                      which will be replaced by the current time.  See the
                      Special Key Codes section of this Manual for details.

                      You can use any of the Script Variables here too.

                      A Carriage Return is generated automatically when
                      "text" has been sent. Note, if you do not want the
                      <CR> to be sent, add a caret ('^') as the last
                      character of the text.  paKet will then NOT generate
                      the <CR>. (It won't send that final caret either!)


   T label,string     Trap -  Goto 'label' if 'string' is received.

                      If 'string' is received at any time during this
                      Script, processing will continue from the nominated
                      'label'.  Note that this happens even if a "Delay"
                      or "Wait" instruction is in progress.

                      For example, say your Script includes the following
                      commands:
                         T MSG,Message waiting
                         T DONE,No Messages Available

                      Then, if the string "Message waiting" is received
                      from the TNC at any time during the processing of
                      this Script, paKet will detect the matching Trap
                      string and will continue processing from the MSG
                      label.

                      And if the string "No Messages Available" is
                      received at any time during the Script, processing
                      continues from the DONE label.

                      The Trap remains set even if nested Scripts are
                      CALLed, so 'label' must be a defined label within
                      all Scripts if the Trap is to be effective.

                      If a Trap is no longer required, it may be disabled
                      by specifying the command without a string. Eg:
                         T DONE,
                      (Note the comma is still required here).

                      Up to 30 Trap strings may be current at any one time.


   W time,string      Wait up to "time" seconds for "string" to be
                      received from the TNC.

                      The received "string" need not start at the
                      beginning of the line.


                               Page 283

                      If "string" is received within the specified "time"
                      the next line of the Script file is skipped,
                      otherwise the next line is executed.

                      Do not enter quotes in "string" unless you are
                      expecting them in the received text.

                      If no string is entered, (eg: W 60, ) paKet will
                      wait up to the time specified but the Wait is
                      considered satisfied as soon as ANYTHING is received!


   X                  Exit the paKet program.
                      This should be used with care. It will not only shut
                      down the Script, it will also shut down the paKet
                      program and will return to DOS.


   YD                 Commence a Binary File download.
                      This assumes the other station is now waiting to
                      send a Binary File to us with either pP or YAPP
                      protocol.


   YU filename        Commence a Binary File upload.
                      This assumes the other station is now waiting to
                      receive a file with either pP or YAPP protocol.

                      'filename' must include full path details unless it
                      is in the current directory.
























                               Page 284